Zum Hauptinhalt springen

Einheit 6 — Response Codes als Diagnosewerkzeug

Was du nach dieser Einheit weißt: Du kannst aus dem Response Code allein eine erste Diagnose stellen — was schiefgelaufen ist, auf welcher Seite das Problem liegt und welche nächsten Schritte sinnvoll sind.

Response Codes sind strukturierte Fehlerdiagnose​

Jede HTTP-Antwort beginnt mit einem dreistelligen Code. Diese Codes sind nicht zufällig — sie folgen einem System:

BereichBedeutung
1xxInformational — Verarbeitung läuft noch
2xxSuccess — Anfrage erfolgreich
3xxRedirection — Ressource hat andere Adresse
4xxClient Error — du hast etwas falsch gemacht
5xxServer Error — der Server hat ein Problem

Die wichtigste Unterscheidung: 4xx bedeutet das Problem liegt auf deiner Seite. 5xx bedeutet das Problem liegt beim API-Anbieter.

Die wichtigsten Codes im Detail​

2xx — Erfolg​

200 OK — Standardantwort für erfolgreiche GET, PUT, PATCH Anfragen. Die Antwort enthält die angeforderten Daten.

201 Created — Ressource wurde erfolgreich erstellt (nach POST). Der Location-Header zeigt oft die URL der neuen Ressource.

204 No Content — Erfolgreich, aber keine Daten zurück. Typisch nach DELETE oder wenn ein PATCH nichts zurückgibt.

202 Accepted — Anfrage angenommen, aber noch nicht verarbeitet. Die Verarbeitung läuft asynchron. Der Server schickt später eine Benachrichtigung oder man muss den Status pollen.

3xx — Umleitungen​

301 Moved Permanently — Die API hat eine neue URL. Alle zukünftigen Anfragen sollen an die neue URL gehen. Häufig wenn APIs migriert werden.

302 Found / 307 Temporary Redirect — Temporäre Umleitung. Aktuelle Anfrage wird umgeleitet, zukünftige sollen weiterhin die ursprüngliche URL nutzen.

In 42°OS: wenn der Post Agent 301/302 meldet, ist die konfigurierte URL veraltet. Neue URL in der Konfiguration eintragen.

4xx — Client-seitige Fehler​

400 Bad Request — Die Anfrage ist syntaktisch falsch. Häufigste Ursachen: fehlerhaftes JSON im Body, Pflichtfeld fehlt, Datentyp falsch. Die Fehlermeldung im Response-Body enthält oft Details.

{
  "error": "validation_failed",
  "details": [
    {"field": "customer_id", "message": "required"},
    {"field": "quantity", "message": "must be positive integer"}
  ]
}

401 Unauthorized — Keine oder ungültige Authentifizierung. Das Token ist abgelaufen, der API Key ist falsch, oder der Authorization-Header fehlt ganz. Lösung: Credentials prüfen, Token erneuern.

403 Forbidden — Authentifizierung erfolgreich, aber keine Berechtigung. Das Konto existiert und ist gültig, hat aber nicht das Recht diese Ressource zu sehen oder diese Operation auszuführen. Lösung: Berechtigungen des API-Kontos prüfen.

401 vs. 403

401 bedeutet: "Ich weiß nicht wer du bist." (fehlende/ungültige Authentifizierung) 403 bedeutet: "Ich weiß wer du bist, aber du darfst das nicht." (fehlende Berechtigung) Das ist eine wichtige Unterscheidung für die Diagnose.

404 Not Found — Die Ressource existiert nicht. Entweder die URL ist falsch, der Endpunkt existiert nicht in dieser API-Version, oder die spezifische Ressource (z. B. Kunde mit ID 42) existiert nicht.

405 Method Not Allowed — Die HTTP-Methode ist für diesen Endpunkt nicht erlaubt. Beispiel: du schickst DELETE an einen Endpunkt der nur GET und POST unterstützt.

409 Conflict — Konflikt mit dem aktuellen Zustand der Ressource. Typisch: du versuchst eine Ressource zu erstellen die bereits existiert (doppelte E-Mail-Adresse), oder du änderst eine Ressource die seitdem von jemand anderem geändert wurde.

422 Unprocessable Entity — Die Anfrage ist syntaktisch korrekt, aber semantisch ungültig. Beispiel: gültiges JSON, aber ein Datum liegt in der Vergangenheit obwohl es in der Zukunft sein muss.

429 Too Many Requests — Rate Limit überschritten. Warten und Retry — Retry-After-Header beachten.

5xx — Server-seitige Fehler​

500 Internal Server Error — Allgemeiner Server-Fehler. Ein Fehler in der API-Logik den der Anbieter nicht abgefangen hat. Oft begleitet von einer Fehlermeldung, manchmal nicht.

502 Bad Gateway — Der API-Server hat eine ungültige Antwort von einem vorgelagerten Server bekommen. Typisch bei Proxy-Konfigurationen oder wenn ein Backend-Service ausgefallen ist.

503 Service Unavailable — Der Server ist überlastet oder in Wartung. Retry nach kurzer Wartezeit ist sinnvoll.

504 Gateway Timeout — Der Server hat zu lange für eine Antwort gebraucht. Bei langen Operationen (große Reports, komplexe Abfragen) normal. Retry sinnvoll.

Diagnose-Schema​

Response Code erhalten
        │
    2xx? ──→ Erfolg. Weiterverarbeiten.
        │
    4xx? ──→ Problem auf meiner Seite
        │        │
        │       400 ──→ Request-Body prüfen: Felder, Typen, Pflichtfelder
        │       401 ──→ Credentials prüfen, Token abgelaufen?
        │       403 ──→ Berechtigungen des API-Kontos prüfen
        │       404 ──→ URL prüfen, Ressource existiert?
        │       429 ──→ Warten, dann Retry
        │
    5xx? ──→ Problem beim Server
                 │
                500 ──→ Fehlermeldung lesen, ggf. beim Anbieter melden
                503 ──→ Retry nach Wartezeit
                504 ──→ Timeout erhöhen oder Retry

Response Body bei Fehlern​

4xx und 5xx Antworten enthalten fast immer einen Body mit weiteren Details. Dieser Body ist das wichtigste Diagnosewerkzeug:

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "No customer with id '42' exists in this account",
    "documentation_url": "https://docs.example.com/errors/CUSTOMER_NOT_FOUND"
  }
}

In 42°OS: nach einem Post Agent immer den Response Body auswerten, nicht nur den Status Code. Der Body enthält die eigentliche Fehlermeldung.

Damit hast du das konzeptionelle Fundament: Was REST ist, wie es sich von SQL unterscheidet, wie HTTP funktioniert, wie Authentifizierung arbeitet, wie ein vollständiger Request aufgebaut ist und wie du Response Codes zur Diagnose nutzt.

Weiter: Einheit 7 — Wo Systeme laufen